home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr05 / ewrtgn10.zip / EWRTFGEN.DOC next >
Text File  |  1993-07-17  |  19KB  |  540 lines
  1.  
  2.  
  3.  
  4.                                EWRTFGEN
  5.  
  6.                  An Extension DLL for E! for Windows (EW)
  7.  
  8.                  (C) Copyright 1992, by L. David Baldwin
  9.                  (C) Copyright 1993, by Patrick Philippot
  10.                           All Rights Reserved
  11.  
  12.  
  13.  
  14.     This package contains an adaptation of Dave Baldwin's RTFGEN
  15.     program, a utility converting an ASCII file complying to a given
  16.     syntax into an RTF file suitable for compilation by the HC, the
  17.     Microsoft Windows help compiler.
  18.  
  19.     You cannot use EWRTFGEN is you don't have installed E! for
  20.     Windows. E! for Windows is a shareware programmer's text editor
  21.     downloadable from the IBMAPP EDITORS library on Compuserve and
  22.     from many other BBSs.
  23.  
  24.     During the process of developping EW, I have found RTFGEN so
  25.     simple and useful that I have decided to use it to produce the
  26.     EW help file.
  27.  
  28.     Once the initial release of EW was ready, I have decided to
  29.     integrate RTFGEN into an EW Extension DLL to make it even easier
  30.     to use. I gratefully thank David for giving me the authorization
  31.     of using his code. EW Extension DLLs are discussed in the
  32.     documentation of E! for Windows. This package is a good example of
  33.     the power of EW Extension DLLs.
  34.  
  35.     EWRTFGEN may not be have all the bells and whistles of other RTF
  36.     generation commercial packages but, after all, the EW Help file has
  37.     been constructed with RTFGEN and we think that it will suit the needs
  38.     of many programmers.
  39.  
  40.     Most of the code in this package is from Dave. I have just
  41.     removed the input routines that were useless since the text was
  42.     retrieved from memory directly. I have also modified the Error
  43.     routine and added some code to process accented characters. The
  44.     translation of RTFGEN into an EW Extension DLL was rather easy
  45.     and only took a few hours.
  46.  
  47.     This package is free and will not be included in the EW
  48.     distribution package.
  49.  
  50.     EWRTFGEN may be copied and distributed freely providing that no
  51.     fee is charged and it is not part of a package for which a
  52.     charge is made.
  53.  
  54.  
  55.     HOW TO USE EWRTFGEN
  56.  
  57.  
  58.     EWRTFGEN.EWD must be copied to your EW\USER directory. While EW
  59.     is running you can load EWRTFGEN from the USER Menu using the
  60.     "Load User Extension..." command. Or you can add it to the
  61.     Autoload List from the same menu to have it loaded automatically
  62.     when EW is run.
  63.  
  64.     Once EWRTFGEN has been loaded, a new item will appear in the
  65.     User Menu: "Translate to RTF".
  66.  
  67.     Select this command to begin the process of translating your
  68.     RTFGEN source file into a RTF file. The following will occur:
  69.  
  70.     1. The current file is systematically saved to make sure that you
  71.     will compile the correct source.
  72.  
  73.     2. The RTF output will be placed in a file in the same directory
  74.     as the source file. This file will have the same name as the
  75.     source file but with a .RTF extension. At this time you can't
  76.     modify this behavior unless you modify the source file. The
  77.     Borland Pascal compiler is required to compile EWRTFGEN.
  78.  
  79.     3. Any error will be reported and displayed in the EW Status
  80.     window at the bottom of the Edit Window. The caret will point to
  81.     the error in the source file.
  82.  
  83.     Your source file is supposed to be compliant to the RTFGEN
  84.     syntax described below. The following text is a slightly
  85.     modified excerpt of the original RTFGEN documentation.
  86.  
  87.     We hope that this package will be useful to many Windows
  88.     developers.
  89.  
  90.  
  91.     Patrick Philippot
  92.     04/10/93
  93.  
  94.  
  95.     =================================================================
  96.                        RTFGEN SYNTAX DESCRIPTION
  97.     =================================================================
  98.  
  99.                                                     February 22, 1992
  100.  
  101.                                 RTFGEN
  102.  
  103.               An ASCII to Rich Text Format Conversion Program
  104.                               Version 1.0
  105.  
  106.  
  107.     OVERVIEW
  108.  
  109.     Normally, to create a help file with the Windows help compiler,
  110.     you must first write a help topic file using a Rich Text Format
  111.     (RTF) word processor. For many, there are two problems here:
  112.  
  113.           1. RTF word processors are expensive.
  114.           2. Learning to use a new word processor is a nuisance and not
  115.              very productive.
  116.  
  117.     RTFGEN solves both these problems by allowing you to use your
  118.     favorite ASCII text editor to produce RTF formatted files
  119.     acceptable to the help compiler.
  120.  
  121.  
  122.         STEPS FOR BUILDING A HELP FILE
  123.  
  124.     The steps required to create a Windows help file using EWRTFGEN
  125.     are:
  126.  
  127.           1. Using EW, create one or more input text files.
  128.              The layout of the input files will be discussed later.
  129.           2. Load EWRTFGEN from the User Menu if it has not been
  130.              Autoloaded.
  131.           3. Run EWRTFGEN by selecting the "Translate to RTF" command
  132.              in the User Menu.
  133.           4. Create a Help Project File (.HPJ) for input to the help
  134.              compiler. This file should reference the RTF files.
  135.           5. Run the help compiler to make the help file.
  136.  
  137.     Steps 4 and 5 are described in the help compiler documentation.
  138.     This documentation deals with the first three steps only.
  139.  
  140.  
  141.     GENERAL EDITING CONSIDERATIONS
  142.  
  143.  
  144.     The use of tabs is required to obtain column alignment with
  145.     proportional fonts. The RTF command, \tab, may be used to
  146.     produce tabs (remember that EW automatically expands tabs to
  147.     spaces).
  148.  
  149.     Here are the default conditions use by RTFGEN:
  150.  
  151.          Helv, 10 point font.
  152.  
  153.          Paragraphs are left justified.  The first line is not
  154.          indented.
  155.  
  156.          Paragraph indentation is set by indentation of the first
  157.          line of the paragraph.
  158.  
  159.          Tabs are spaced every 720 twips (about 6 default
  160.          characters).
  161.  
  162.     Any of these defaults may be changed globally for the whole
  163.     document or locally at the topic, paragraph, or even character
  164.     level.
  165.  
  166.     RTFGEN and/or the RTF language have special use for the
  167.     following characters:
  168.  
  169.         `    (grave accent) Used to mark end of paragraphs.
  170.         [,]  Used to mark jumps and definitions.
  171.         {,}  Used to mark areas where font characteristics will change.
  172.         \    Used as a command start character.
  173.  
  174.     When these characters are to be used in the text, they should be
  175.     preceded by a '\'. Thus, '\[' will cause the left bracket to be
  176.     inserted in text and '\\' will result in a single backslash
  177.     being inserted in text.
  178.  
  179.     (*...*) may be used to insert comments within the text.
  180.  
  181.  
  182.  
  183.     ASCII INPUT FILE LAYOUT
  184.  
  185.     The input file for RTFGEN should have the following sections:
  186.  
  187.         1. An optional document header.
  188.         2. The command, \docstart, to mark the start of the document.
  189.         3. One or more topics consisting of:
  190.              a. A topic header.
  191.              b. A row of 5 or more '='s marking the start of the topic
  192.                 text.
  193.              c. The topic text.  This is basically the text to be
  194.                 displayed in the help file.
  195.              d. A row of 5 or more '-'s marking the end of the topic.
  196.         4. The command, \docend, marking the end of the document.
  197.  
  198.  
  199.     Document Header
  200.  
  201.     The optional document header may contain commands which will be
  202.     interpreted globally throughout the document. Commands changing
  203.     the font, font size, or first line indent might be appropriate
  204.     here.
  205.  
  206.     The \docstart command follows the document header to mark the
  207.     start of the topics.
  208.  
  209.            Example:
  210.  
  211.            \f0 \fs24  (*Times Roman font, 12 pitch for entire file*)
  212.            \docstart
  213.  
  214.     Topic Header
  215.  
  216.     The topic header contains commands defining build tags, context
  217.     strings, title, keywords, and browse sequence number as
  218.     appropriate for the topic. Topic global formatting commands may
  219.     also be included. The topic header section is terminated with a
  220.     row of 5 or more '='s.
  221.  
  222.            Example:
  223.  
  224.            \title Table of Contents`
  225.            \topic contents`
  226.            \keyword contents`
  227.            \f0 \fs24   (* Times Roman font, 12 pitch for this topic *)
  228.            ============  (* end of topic header *)
  229.  
  230.     Topic Text
  231.  
  232.     Text for the topic is entered here. Rules for text entry are:
  233.  
  234.     Paragraph ends are marked with a grave accent, '`'
  235.  
  236.     Blank lines will appear as blank lines.
  237.  
  238.     By default, paragraphs are left justified. The indenting of the
  239.     paragraph is set by the indenting of the first line of the
  240.     paragraph. Indenting of lines after the first is ignored.
  241.  
  242.     Carriage returns and linefeeds within the paragraph are ignored
  243.     as far as the final results are concerned.
  244.  
  245.     Commands may be interspersed within the text for special
  246.     effects. The commands themselves won't appear in the final
  247.     result.
  248.  
  249.            Examples:
  250.  
  251.            |   Here is a typical paragraph.  It will appear in the font
  252.            |   and pitch specified in the topic header or document
  253.            |   header.  It is left justified and indented by 360 twips
  254.            |   because the first line is so indented.  The paragraph
  255.            |   is terminated with a grave accent character.`
  256.  
  257.            |   \b\fi480 Here is another paragraph.  It will appear in
  258.            |   bold font because of the \b command.  It will also be
  259.            |   be indented by 360 twips and left justified.  The
  260.            |   \fi480 will cause the first line of the paragraph
  261.            |   to be indented an additional 480 twips.`
  262.  
  263.  
  264.  
  265.     COMMAND SYNTAX
  266.  
  267.     Commands for RTFGEN and RTF commands passed thru to the help
  268.     compiler have a similar syntax. Commands start with a backslash
  269.     followed by a LOWERCASE alpha symbol. Some RTF commands have a
  270.     numerical value attached. Some RTFGEN commands have an
  271.     additional parameter string.
  272.  
  273.         Examples:
  274.  
  275.         \box
  276.         \topic <topic name>
  277.         \fs24          RTF command with number
  278.         \fi-720        '-' sign may be used if appropriate
  279.  
  280.     When commands are mixed with text, a trailing space may be
  281.     required as a delimiter. The first space following a command is
  282.     considered part of the command--additional spaces are part of
  283.     the text.
  284.  
  285.  
  286.     RTFGEN COMMANDS
  287.  
  288.     Topic Header Commands
  289.  
  290.         \buildtag <parameter string>`
  291.         \topic <parameter string>`
  292.         \title <parameter string>`
  293.         \keyword <parameter string>`
  294.         \browse <parameter string>`
  295.  
  296.     These commands correspond to the *, #, $, K, and + footnotes
  297.     described in the help compiler documentation. Each topic header
  298.     will contains one or more of these commands as appropriate
  299.     (ordering is unimportant).
  300.  
  301.     The parameter string should--
  302.  
  303.         have format and contents exactly as described in the help
  304.         compiler documentation for the equivalent footnote.
  305.  
  306.         be entirely on one line.
  307.  
  308.         be terminated by an end of paragraph mark (grave accent).
  309.  
  310.     More than one \keyword command may be used if the number of
  311.     keywords would exceed the allowable editor line length.
  312.  
  313.         Examples:
  314.  
  315.         \topic proc_deleting_text`
  316.         \title Deleting Text`
  317.         \browse procedures:020`
  318.         \keyword delete;clipboard`
  319.  
  320.  
  321.     Cross References
  322.  
  323.     Cross references may be included in the topic text using the
  324.     format:
  325.  
  326.         [<green text>:<context>]
  327.  
  328.     where the brackets indicate a cross reference, <green text> will
  329.     appear highlighted, and <context> is the topic context string
  330.     for the jump destination.
  331.  
  332.         Example:
  333.  
  334.         To change the color of an existing object, the object is first
  335.         [selected:selecting].  Its color may then be changed.`
  336.  
  337.     Definitions
  338.  
  339.     Definitions may also be included in topic text by enclosing them
  340.     in double brackets:
  341.  
  342.         [[<green text>:<context>]]
  343.  
  344.         Example:
  345.  
  346.         Each space is equivalent to 120 [[twips:twip_def]].`
  347.  
  348.  
  349.     Bitmap Commands
  350.  
  351.         \bml <filename>
  352.         \bmr <filename>
  353.         \bmc <filename>
  354.  
  355.     These commands are used to insert bitmaps within the topic text.
  356.  
  357.         Example:
  358.  
  359.         A bitmap may be placed in a sentence \bmc arrow.bmp , just like
  360.         any character.`
  361.  
  362.     It's also possible to use a bitmap to cause a jump or bring up a
  363.     definition as:
  364.  
  365.         Press here [\bmc button.bmp:jump_dest] for more information.`
  366.  
  367.  
  368.     Block Formatting Commands
  369.  
  370.         \blockstart <commands>`
  371.         \blockend
  372.  
  373.     The blockstart, blockend commands define a block over which a
  374.     set of RTF commands will apply. These commands are used mainly
  375.     when laying out tables where formatting is somewhat complex. An
  376.     example of their use is given later in the tabbing commands
  377.     section.
  378.  
  379.     The block formatting commands may be nested to a level of 4.
  380.  
  381.  
  382.     RTF COMMANDS
  383.  
  384.     RTF commands have no effect on RTFGEN but rather are passed
  385.     along to the help compiler to achieve certain effects.
  386.  
  387.     In the following, some of the RTF commands which seem
  388.     appropriate for use in help files are listed. While there are a
  389.     good many listed, keep in mind that in most help files only a
  390.     few will be required.
  391.  
  392.     Font Commands
  393.  
  394.     Fonts are refered to by number. Number vs font is set by the
  395.     font table in the HEADING file. For the HEADING file supplied:
  396.  
  397.         0  Times Roman
  398.         1  Symbol
  399.         2  Helv (default)
  400.         3  Courier
  401.  
  402.     You can add fonts or change the order by editing the HEADING
  403.     file.
  404.  
  405.         \f000            change to font 000
  406.         \fs000           set font size in half points
  407.         \plain           plain text (as opposed to bold, italic)
  408.         \b               bold
  409.         \i               italic
  410.         \ul              underline
  411.         \uldb            double underline
  412.         \uld             dotted underline
  413.         \strike          strikethru text
  414.  
  415.     The scope of font commands may be document global (placed in
  416.     document header), topic global (placed in topic header),
  417.     paragraph global (placed at start of paragraph), or character or
  418.     word global (scope defined with {..}).
  419.  
  420.         Examples:
  421.  
  422.         \b This paragraph will appear in bold text.`
  423.  
  424.         This paragraph is {\ul mostly} in plain text with a {\b bold}
  425.         and an {\i italicized} word.  {\f0 Fonts and \fs30 pitch} can be
  426.         temporarily changed.`
  427.  
  428.     Paragraph Commands
  429.  
  430.  
  431.         \par             end of paragraph.  RTFGEN handles this.
  432.         \pard            reset to paragraph defaults.  RTFGEN handles
  433.                          this.
  434.         \li000           left paragraph indent in twips.  RTFGEN
  435.                          handles this.
  436.         \fi000           first line indent.  May be negative.
  437.         \ri000           right paragraph indent.
  438.         \sb000           space below paragraph.
  439.         \sa000           space above paragraph.
  440.  
  441.         \ql              left justified (default)
  442.         \qc              paragraph is centered
  443.         \qr              right justified
  444.  
  445.         \box             paragraph is surrounded by a box
  446.         \brdrl           left border
  447.         \brdrb           bottom border
  448.         \brdrr           right border
  449.         \brdrt           top border
  450.  
  451.     The scope of paragraph commands may be document global (placed
  452.     in the document header), topic global (placed in the topic
  453.     header), or paragraph global (placed at the start of the
  454.     paragraph).
  455.  
  456.         Examples:
  457.  
  458.         |\box\qc This paragraph is surrounded by a box and is centered.`
  459.  
  460.         |      \fi-360 The first line of this paragraph overhangs by
  461.         |      about 3 characters.  Note that RTFGEN has already
  462.         |      indented the paragraph 720 twips because of its
  463.         |      interpretation of
  464.         |      the 6 character indentation on the first line.`
  465.  
  466.  
  467.     Tabbing Commands
  468.  
  469.     In RTFGEN, either the tab character or the RTF command, \tab,
  470.     may be used to produce a tab in the help file. By default, tabs
  471.     are every 720 twips (about 6 characters). If neat columns are
  472.     desired with proportional fonts, tabs are a must.
  473.  
  474.         \tab             causes tab
  475.         \tx0000          defines tab position in twips.  May be used
  476.                          multiply and should be used prior to using
  477.                          tabs.
  478.  
  479.     The following should be used just prior to the \tx000 command to
  480.     which they are to apply:
  481.  
  482.         \tqr             tab is right justified
  483.         \tqc             tab is centered
  484.  
  485.     The \blockstart..\blockend commands may be used to prepare the
  486.     format for a table.
  487.  
  488.         Example:
  489.  
  490.         \blockstart \li1000\tqr\tx2700\tqc\tx4000` (* tab setup *)
  491.         \ul Left\tab Right\tab Centered`  (* underlined table heading *)
  492.         Data1\tab 1234\tab 12345`
  493.         ABC \tab 12\tab 3333444`
  494.         XYZdef\tab 45678\tab 9`
  495.         \blockend
  496.  
  497.  
  498.     SOURCE CODE
  499.  
  500.     The cosurce code is provided for those who may want to modify the
  501.     package themselves. It's also a good example of EW Extension DLL.
  502.     Please don't upload a modified package without notifying us.
  503.  
  504.     The EW API documentation is available for EW registered users only.
  505.  
  506.  
  507.     REFERENCES
  508.  
  509.     The following files may be found on CompuServe in several
  510.     locations. To find them use the IBM file finder (GO IBMFF).
  511.  
  512.         RTF.TXT          Info on the RTF syntax.  Many more commands
  513.                          are listed than given here.
  514.         QDHELP.LZH       Another system to produce help files using an
  515.                          ASCII editor.
  516.  
  517.  
  518.     COPYRIGHT
  519.  
  520.  
  521.     Original RTFGEN package:
  522.  
  523.               (C) Copyright 1992 by L. David Baldwin.
  524.                         All Rights Reserved
  525.  
  526.     EWRTFGEN
  527.  
  528.               (C) Copyright 1993 by Patrick Philippot.
  529.                         All Rights Reserved
  530.  
  531.     EWRTFGEN may be copied and distributed freely providing that no
  532.     fee is charged and it is not part of a package for which a
  533.     charge is made.
  534.  
  535.     Please report all bugs, suggestions, and problems to Dave
  536.     Baldwin, CompuServe ID #76327, 53. However, problems related to
  537.     EWRTFGEN itself (that is, problems not related to the RTF code
  538.     generation) have to be reported to Patrick Philippot, Compuserve
  539.     ID #72561,3532.
  540.